Release notes for Myopic v2010.02.10 beta

These are the release notes for the 010.02.10 beta version of the chess program Myopic.

Directories:
  myopic -- Main directory
  myopic/Source -- All source files for the desktop version
  myopic/Arduino -- Contains the single Arduino Mega specific source file

Myopic is designed to run both on desktop (or notebook) machines as well as on small systems with limited RAM.  The desktop version of the program has been tested with Mac OS/X (both PowerPC and Intel CPUs), Linux, and Cygwin.  The Arduino version of Myopic has been tested with the Arduino Mega (Atmel ATmega1280 with 128 KB flash, 8 KB RAM); it should also work on similar small systems, but NOT on the Arduino Duemilanove that has only 32 KB flash and 2 KB RAM.

--------

Building Myopic from the included source files requires an ANSI C++ toolchain such as is provided by the GCC compiler system.  This toolchain is available for Mac OS/X with the optional and free Xcode IDE from Apple.  The toolchain is also available for free on nearly all Linux distributions and is often installed by default.  Some Linux distributions like Ubuntu require the use of a package manager to retrieve and install the toolchain.  The Cygwin environment has a special "setup.exe" program that can be used to acquire the toolchain.  For those working with the Microsoft Visual C++ IDE, I wish you good fortune.

To build and run the desktop version of Myopic on a Unix or Unix-like system, follow this ten-fold way:

1) Make a backup copy of the Myopic distribution in case of unforeseen problems.

2) Start a terminal emulator and interactive shell.

3) Set the shell's current directory to the myopic/Source directory.

4) Issue the command:

  g++ -O3 -pipe -Wall -o myopic *.cpp

5) The resulting executable can be run with the command:

  ./myopic

6) Myopic uses the prompt string "[] " to request user input.  (By the way, this is from APL's quad operator.)  To see a brief help string, enter the command "hm" (help me).  To quit the program, enter "qp" (quit program).  Note that all of Myopic's command names are two characters long.  Some take parameters and some don't.

7) Myopic has several boolean value options that can modify program behavior.  Each option can be set (by the "so" set option command) or reset (by the "ro" reset option command).  Initially, all options are reset when Myopic starts.  The list of currently set options is given by the "do" (display options) command.  Note that all of Myopic's option names are two characters long.

8) To just play chess, enter a move and wait for the program to reply.  Myopic is strict about chess move input and will only accept SAN (Standard Algebraic Notation) moves.  To see a list of valid SAN moves, enter the "dm" (display moves) command.  The "db" (display board) command will show a compact ASCII chessboard with the current position.  The "ds" (display status) will display just about everything there is to display.

9) To get a hint, use the "gs" (go search) command.  To switch sides, try the "gp" (go play) command.  To let the program play both sides to the end of the game, use the "gg" (go game) command.  To take back a move, use the "TB (take back move) command.  For a new game, enter the "ng" (new game) command.  The "sf" (set FEN position) will set up a chess position using the six field Forsyth-Edwards Notation specification of the desired position as the command's parameters.  Use "df" (display FEN) to show the FEN of the current position.

10) To change playing strength, set a time limit with the "st" (set time limit) command; its single parameter is the number of seconds of time to use per search.  To limit the search depth, use the "sd" (set depth limit) command; its single parameter is the count of search iterations to be used in a search.  Both the time and depth limits are active for a search.  The initial time limit is five seconds and the initial depth limit is twenty ply (but the latter number may vary depending on certain implementation details).

--------

Building Myopic for the Arduino Mega requires a bit more work than building it for a desktop system.  As with the case of a desktop target, an ANSI C++ toolchain is needed and this can be provided by using the Arduino IDE that's available from the http://arduino.cc web site.  Full instructions for using the IDE are also available from the Arduino site.

To build/run Myopic for/on the Arduino Mega:

1) Before experimenting with Myopic on the Arduino Mega, try the various simple examples that come with the Arduino IDE.  It's better to solve integration problems sooner rather than later.

2) Start the Arduino IDE on a desktop machine and initialize a new sketch with the file "myopic.pde" that resides in the myopic/Arduino directory of the Myopic distribution.

3) Within the IDE, select the menu pick "Tools/Board/Arduino Mega".  Connect the USB cable to the desktop machine at one end and with the Arduino Mega board at the other.  Select the appropriate link from the "Tools/Serial Port" menu pick.

4) Within the IDE sketch editor window, locate the C++ preprocessor include directives that reference Myopic's C++ source files (all have a "cpp" file extension).  Yes, there are a lot of them.  And yes, Myopic's main program "main.cpp" is purposely not referenced as it's for the desktop version only.

5) Each of these source include directives most likely needs to be changed to point to the myopic/Source directory as it was installed.  So there may be some typing/editing to do, but it only has to be done once.  Note that the Myopic sources should not be manually copied into wherever the Arduino IDE stores the the main sketch due to name collisions.

6) Compile Myopic with the "Sketch/Compile" menu pick.

7) After a successful compilation, upload the executable to the Arduino Mega board with the "Sketch/Upload' menu pick.  An upload will take about a minute as the executable is over 100 KB in length.

8) Start up the Serial Monitor window and, if needed, press the reset button on the Arduino Mega board.  (Make sure that the Serial Monitor is set at its default speed of 9,600 baud.)  The Myopic sign-on banner should appear along with a command prompt.

*** IMPORTANT NOTE *** Due to an IDE bug, a "$" character MUST be appended to each user input line sent via the Serial Monitor; this is needed to signal an end-of-line condition to Myopic.  This "$" end-of-line signaling is not to be used with the desktop version of Myopic, nor is it needed when using a decent terminal emulator (e.g., the Unix "screen" program) to connect to the Arduino Mega board.

9) The Arduino Mega version of Myopic does all that the desktop version can do, albeit rather more slowly.  The one exception is the "bb" (build book) command that is desktop-only.

10) See the program source for more details.

--------

The SparkFun 8x8 RGB LED backpack is an optional addition to Myopic when running on an Arduino Mega or a similar and compatible board.  When used, the backpack is connected to the board using the SPI communication bus and provides a multicolor display of Myopic's internal chessboard.  Details of connecting the backpack are presented in the Arduino source file myopic.pde and these include the wiring information.  The backpack display will update whenever a move is played.  It will also provide a dynamic display or the chessboard while Myopic is searching for a move; the display is updated at a rate of 4 Hz, twice that of the pin 13 activity LED.  The display is also updated during execution of the "em" (enumerate movepaths) command; the display is refreshed after each move is executed and retracted during an enumeration.  Note that the "fm" (fast movepath enumeration) does not update the display.

--------

The "bb" (build book) command will build an opening library book.  As this command requires a filesystem, it works only with Myopic in desktop mode and not when it's running on an Arduino.  The "bb' command takes two parameters: the name of a text file containing PGN game data, and the name of a code file for output of the compiled opening library.  The book builder output file will contain up to 4,095 position/move combinations given a sufficiently large collection of games.  To install the new opening library, the code file is renamed "OpeningBookCodes" and placed in the "Source" directory containing Myopic's source files.  Myopic is then recompiled to finish the process.  Note: if less than 4,095 position/move codes are generated, then the actual number of codes must be entered into the source of the file Book.h as the new value of the symbol "BookEntryLen".

The book that comes with the Myopic source distribution was produced from a PGN file that had over two million games and took about nine hours of processing time to make.

--------

Myopic has two known overflow failure modes.  The first of these is a move stack overflow and it is the result of a search where the time or limit values are too high for a given position.  This has not occurred during testing but might occur elsewhere.  If Myopic does detect a move stack overflow, it will output the overflow diagnostic and stop.  The recommended treatment of the problem is to use a shorter time limit or a lesser depth limit.

The second overflow failure mode is a call stack overflow.  (Arduino Mega only)  This may occur if a search runs for a long time and goes too deep. Should this happen, the program will likely either freeze or restart.  Fortunately, this problem has not occurred when running tests with reasonable search time limits.

Some counters are 32 bits long and may overflow for long searches or deep movepath enumerations.  These overflows will cause errors in some numeric output data but will not crash the program nor will they affect move selection.  It is possible that a future release will use 64 bit counters to avoid counter overflow.

The Arduino Mega millisecond counter will overflow after 49 plus days of continuous operation.  This will confuse Myopic and so the Arduino board should be reset at least once every 49 days if it's running non-stop. 

Entering ridiculously large values for a half move counter or a full move number in a FEN specification will result with a silent mapping to more usable values.  Similar silent changes are made for the numeric parameters to some commands.

Ridiculously long text input to the command prompt will be silently truncated.  Also, only the first eight tokens on a command input are processed. 

If an end of file ASCII code (0x04) is entered at the command prompt, the program will treat this as an end of command input and will stop.

--------

Advanced users can free up more Arduino RAM by changing the IDE's HardwareSerial library source files to remove the second, third, and fourth Serial object instances.  Do this only if you REALLY know how to do it, as the build system can be easily broken if the changes are not done correctly.  One positive result of performing this change is to greatly reduce the chance of a call stack overflow, both with Myopic or any other program running on an Arduino Mega.

--------

Myopic's text strings are located in the Constants.cpp source file.  These strings can be changed to a different language to produce a version of Myopic for a different locale.  Likewise, the single letter names for the chess pieces can be changed as well by modifying the appropriate character literals in the same file.  Sorry, but multibyte characters are not supported.

--------

A user interrupt feature is available.  The AVR interrupt number zero, mapped to Arduino pin two, is now (optionally) enabled.  When the board detects a rising edge on pin two, it generates an interrupt that is sent to Myopic.  If Myopic is currently running a search for a move, then the search is interrupted and will terminate with whatever best analysis has been generated at that point.

Physically, the interrupt functionality is realized by wiring a pushbutton into the circuit with one side connected to 5 V (or 3.3 V as the case may be) and the other side connected to Arduino/Arduino Mega pin two.  For reliable operation, pin two should have a pull-down resistor connected.

Currently, only the search is interrupted.  The "gg" command (go and play to end of game) and "pt" command (play an infinite sequence of games) will continue with more searches.  These commands will likely also be fully interrupted in a future revision.

The interrupt facility is not yet implemented for the desktop (non Arduino) running mode.

--------

Plans for future versions include:

1) Much improved positional scoring and some improvement to the search.

2) A command processor that can connect to the Xboard GUI.

3) A pushbutton input and an LED/LCD character output as an interface when running on an Arduino.

4) Pondering; a speculative search is run while waiting for the opponent to make a move.

5) Producing a version for other small systems that use different microcontrollers; vendor contributions will be helpful here.

6) Adding game clocks that will support variable time limits given to the search.

7) Adding a problem solving mode that can process an entire file of chess positions (desktop mode only).

Suggestions for improvements are quite welcome.

